<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<title>ProMRDS Maze Simulator Documentation</title>
<link href="../Styles/Standard.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table width="100%">
<tr>
<td width="200"><a href="http://www.ProMRDS.com"><img src="../Images/HomeIcon.gif" alt="ProMRDS Home Page" border="0" width="200" height="60" /></a></td>
<td width="*" align="center"><img src="Images/MazeSimulator.gif" alt="Maze Simulator" /></td>
</tr>
<tr>
<td colspan="2"><hr /></td>
</tr>
</table>

<div class="page">
<p class="heading"><span class="smallhead">Professional</span><br />&nbsp;&nbsp;&nbsp;Microsoft Robotics Developer Studio<br />
<a href="http://www.ProMRDS.com" onmouseout="Home.src='../Images/Home.gif';" onmouseover="Home.src='../Images/Home_f2.gif';"><img name="Home" src="../Images/Home.gif" width="150" height="25" border="0" alt="Home Page" /></a>
<a href="../ReadMe.htm" onmouseout="Contents.src='../Images/Contents.gif';" onmouseover="Contents.src='../Images/Contents_f2.gif';"><img name="Contents" src="../Images/Contents.gif" width="150" height="25" border="0" alt="Book Contents" /></a>
<a href="ReadMe.htm" onmouseout="ThisChapter.src='../Images/ThisChapter.gif';" onmouseover="ThisChapter.src='../Images/ThisChapter_f2.gif';"><img name="ThisChapter" src="../Images/ThisChapter.gif" width="150" height="25" border="0" alt="This Chapter" /></a>
</p>

<h1>Documentation for Maze Simulator</h1>

<h2>Background</h2>
<p>
The Maze Simulator creates simple block worlds in the MRDS Simulator using a bitmap
image as the template. This template effectively specifies both the height and the
color or texture of the walls or other rectangular objects in your maze. In addition,
you can have spherical objects.
</p>
<p>
This page contains basic instructions for using the Maze Simulator program. Please read through
the whole page before you attempt to use it. Most of your questions
should be answered by this page.
</p>
<p>
To change the way that the Maze Simulator works, you edit the config file which is:<br />
ProMRDS\Config\MazeSimulator.Config.xml<br />
Most of the settings should be self-explanatory. However, the following sections describe
them in more detail.
</p>

<h3>Marking the Walls in the Bitmap Image Template</h3>
<p>
The default maze bitmap is called ModelLarge.bmp and should look basically like
the picture below.
</p>
<img src="Images/ModelLarge.gif" alt="Default Model" />
<p>
The dark grey background color in the image is the floor, and other
objects are mapped by default to the 16 basic colors that are used in a
Windows Paint (BMP) 16-color image: Black, Red, Lime Green, Yellow, Blue, Magenta, Cyan,
White, Light Grey, Dark Grey, Maroon, Dark Green, Olive, Navy, Purple, Cobalt.
It is not necessary to use exactly these colors (as you can see from the example above).
They just need to be close to the respective colors.
</p>
<p>
When the Maze Simulator reads the bitmap, it assumes that the top-left pixel is 
part of the floor and uses this color to identify the rest of the floor. This pixel
does not have to be one of the standard colors, and in fact it should be different
from them so that you have all 16 colors available for use.
</p>
<p>
Your walls cannot go all the way to the edge in the top corner because the top-left
pixel identifies the floor color. However, this is not a problem because the maze
will be centered on the origin in the simulated world, so you can
put a border around the maze using the floor color and you won't even notice!
</p>
<p>
Note that the image can be in any of the standard formats: BMP, GIF, JPG. You can use
Microsoft Paint, for example, to draw your maze. In particular, you might want to use
the 16-color mode in Paint. However, in this case, you will lose one color as the
floor color, i.e. you will only have 15 available for walls.
</p>
<p>
If you want to change the maze, you can of course edit the program. However,
most of the parameters for the program are available in the saved
state file (config file). This allows you to completely reconfigure the
maze by just editing an XML file. The file called
MazeSimulator.Config.xml (included in the package) is located
in the ProMRDS\Config folder. (This is under the location where you installed MRDS.)
</p>
<p>
The name of of the maze bitmap file is in the Maze attribute, e.g.<br />
<tt>&lt;Maze&gt;\ProMRDS\Chapter9\MazeSimulator\ModelLarge.bmp&lt;/Maze&gt;</tt><br />
Notice that the path starts with a backslash. This means that the path begins
in the &lt;MRDS&gt; root directory.
</p>
<p>
Alternatively, you can just enter a filename and then place
the file in the &lt;MRDS&gt;\store\media\Maze_Textures folder. (In this case,
the filename must not begin with a backslash.)
</p>

<h3>Ground Texture</h3>
<p>
The texture filename that is used for the ground can be specified.
Note that this file must be in the store\media folder, or a subdirectory
of this.
</p>

<h3>Color Mapping</h3>
<p>
With the default settings, the colors are mapped directly as you would expect,
i.e. red becomes red! However, you can change the color mapping in two different
ways: change the values in the config file; or edit the program and recompile.
(They are defined in the MazeSimulatorTypes.cs file as part of the
MazeSimulatorState class.)
</p>
<p>
To change the colors using the config file, look for the section
called WallColors. This contains a list of 16 Vector3 items.
Each of these has X, Y and Z values which actually correspond to
Red, Green and Blue (RGB). You can set these values between 0 and 255.
So for example, Cobalt Blue is 0, 128, 128.
</p>
<p>
NOTE: Color mapping is overridden by Texture Mapping (explained below).
You must leave a "blank" in the list of texture files if you want to
use a color instead. 
</p>
<h3>Texture Mapping</h3>
<p>
A set of texture files is supplied in the images subdirectory under the MazeSimulator
directory. <b>You must copy these to your store\media directory under your
MRDS root directory.</b>
</p>
<p>
These texture files give you 16 basic solid colors (although you don't need them
because these are the default colors!) If you don't like them, open them in
Paint and change the colors. You do not need to use texture files if you only want
solid colors -- See the previous section on Color Mapping.
</p>
<p>
In addition, there are a couple of actual textures - water, sand, wood.
This can also be used to cover your walls and other objects. The CheckerBoard.bmp
is a simple black and white checkerboard that is used in the sample config file
as the texture for the balls (spheres).
</p>
<p>
If you want to change the textures that are used for the different colors,
you can of course edit the program. However, they are also available in
the config file in the WallTextures section. This is a list of nine
strings which are the filenames. The default path is the
store\media directory.
</p>
<p>
NOTE: You can leave a texture "blank" by entering an empty
string as follows:<br />
&lt;string /&gt;<br />
This will allow you to use Color Mapping instead of a texture.
If you don't want any textures, you can actually delete all of
the strings in the WallTextures section. The next time you
run the program, it will rewrite the file with a set of empty
strings.
</p>
<h3>Height Mapping</h3>
<p>
The Maze Simulator uses a height table that maps each color to a 
(possibly) different height. You can change this table if you edit the code and
recompile, or you can simple edit the xml config file. The heights are
in the section called HeightMap in the config file. It is a simple list
of 16 float values, one for each color.
</p>
<p>
Note that if you change the code, you can specify a "height" that is really small,
as in 0.01, and the "blocks" will look like patches on the floor. (See the
<a href="LineFollowing.htm">Line Following</a> example). You can also
set up a really, really tall blocks, e.g. with a height of 1,000,000.
</p>
<p>
There is an overall scale factor applied to the heights called HeightScale.
</p>
<p>
The blue area in the corner of the default model is a swimming pool (if you
use the supplied config file)! Or is it a pool? Perhaps it's only a
mirage. You figure it out!
</p>
<p>
Note that the Simulator can use a greyscale image as a height field. This is
much more sophisticated than this maze simulator. However, the maze
simulator is much easier to get started with.
</p>
<h3>Mass Mapping - Changing the Mass of Objects</h3>
<p>
In previous versions of the program, all the walls had infinite mass (weight).
This meant that the robot could not push the walls around, and that is
probably what you wanted. However, it is more fun if you can move things around,
especially now that you can create spherical objects, i.e. balls! (See below for
instructions on creating spheres.)
</p>
<p>
The config file now contains a section called MassMap. This is similar to the
HeightMap and has one value for each of the 16 colors. The mass is in kilograms.
</p>
<p>
To create
a simulation object with infinite mass you actually specify a value of zero for
the mass. This is the default value. If you want to move an object around, then
you can use small masses like a few kilograms. In the sample config file, the
mass for the balls is set to 1 kg.
</p>
<p>
Note that if you change the mass of a wall, then if might fall over on top of the
robot if the robot bumps into it!
</p>
<h3>Creating Spherical Objects</h3>
<p>
There is a section in the config file called UseSphere that contains a set of
16 boolean values. If you set one of these to <b>true</b>, then any pixels of the
corresponding color will be used to create spheres instead of walls (blocks).
</p>
<p>
"Height" does not
really make sense for these objects, so their size is calculated differently.
You draw a square or rectangle into the bitmap image of the desired size for
the sphere and the program figures out the radius.
</p>
<p>
The size of spheres is determined by the
size of the "blob" in the bitmap image. You probably want to create squares,
although the program will use the diagonal size of a rectangle if you the object
you create is not square. This size is used to determin the radius of the sphere
and it will be placed into the simulation at the center of the square/rectangle. 
</p>
<p>
Spheres have their own scaling factor called SphereScale.
</p>
<p>
NOTE: If you want your spheres to bounce like balls, then you might have to
adjust the Bounce Threshold (see below).
</p>

<h3>Camera Pose</h3>
<p>
The camera on the simulated Pioneer can be moved and tilted. The position of the
camera is specified relative to the center of the robot. The camera tilt is given
as an angle of rotation about the X axis. The following example is for line following
and has the camera moved forwards (Z = -0.5) and tilted down (-85 degrees):<br />
<tt>
&lt;CameraPosition&gt;<br />
&nbsp;&nbsp;&lt;X xmlns="http://schemas.microsoft.com/robotics/2006/07/physicalmodel.html"&gt;0&lt;/X&gt;<br />
&nbsp;&nbsp;&lt;Y xmlns="http://schemas.microsoft.com/robotics/2006/07/physicalmodel.html"&gt;0.5&lt;/Y&gt;<br />
&nbsp;&nbsp;&lt;Z xmlns="http://schemas.microsoft.com/robotics/2006/07/physicalmodel.html"&gt;-0.5&lt;/Z&gt;<br />
&lt;/CameraPosition&gt;<br />
&lt;CameraTiltAngle&gt;-85&lt;/CameraTiltAngle&gt;<br />
</tt>
</p>
<p>NOTE: If you inadvertently wipe the config, then the position will default to all
zeros. When you look at the robocam you will have a strange view from out underneath
the robot.
</p>

<h3>Grid Size</h3>
<p>
There are two parameters that affect the grid that is used for the walls:
WallBoxSize and GridSpacing. The WallBoxSize is usually set to 0.98 or 0.99.
This means that a pixel in the bitmap occupies almost an entire cell. If you
make it much smaller than this, then the walls will not join at the corners.
However, if you set it to 1.0 then the walls might blow apart when the
simulation begins due to small roundoff errors that make the Simulator
think the walls have collided.
</p>
<p>
The GridSpacing is a scale factor that adjusts the size of the cells. Each
pixel in the bitmap is a cell, so typically the GridSpacing might be 0.1
(100cm) or even 0.01 (10cm).
</p>

<h3>Bounce Threshold</h3>
<p>
The BounceThreshold parameter specifies the "bounciness" of surfaces in the
simulation. Unfortunately, if you wipe the config this will default to zero,
which is VERY bouncy. The actual default in the Simulator is -2, which is
pretty dead. To get a reasonable bounce, try -0.25.
</p>

<h3>Robot Starting Position</h3>
<p>
The initial position of the robot can be specified in terms of the grid cells
that make up the maze. There are two parameters: RobotStartCellRow and
RobotStartCellCol.
</p>
<p>
Each pixel in the bitmap corresponds to a cell, scaled by the GridSpacing
parameter. The origin is in the middle of the bitmap, so usually a setting
of (0,0) will be OK.
</p>
<p>
NOTE: If you put the robot inside a wall, when the simulation starts
it will be explosively expelled from the wall! It might go flying up in
the air, and almost certainly will land on its side.
</p>

<h3>Selecting a Robot Type</h3>
<p>
There are two types of simulated robots available:<br />
Pioneer 3DX; and<br />
Lego NXT
</p>
<p>
To select the type of robot, you need to edit the config file and change the
value of RobotType to either Pioneer3DX or LegoNXT (with no spaces). Note that
the Pioneer robot has a camera mounted on top, but the Lego robot does not.
</p>

<h2>Requirements and Installation</h2>
<p>
To get started, you need to install the Microsoft Robotics Studio on your PC.
It is available for free for non-commercial use from <a href="http://msdn.microsoft.com/robotics/downloads/">Download Site</a>.
It requires the .NET 2.0 runtime, which is also available from Microsoft's download site.
</p>
<p>
If you want to
write your own code, then you will need Visual Studio 2005, but since there is not much
point in using a Robotics Software Development Kit (SDK) without a compiler, I assume that
you already have Visual Studio. In that case, you also have .NET 2.0 already installed.
</p>
<p>
Download the package from the ProMRDS web site. It is a DssDeploy
self-extracting executable file. When you run it, it will automatically
copy all the files
into your MRDS root directory. This will create a folder:<br />
<tt>&lt;MRDS&gt;\ProMRDS\Chapter9\MazeSimulator</tt><br />
where &lt;MRDS&gt; is the directory that your copy of MRDS was installed into.
The default is &quot;C:\Microsoft Robotics Studio (1.5)&quot; which corresponds to
the Version 1.5 release.
Notice that MRDS is installed on the C: drive. If yours is on a different
drive, then you will have to modify several settings in the Visual Studio
project before compiling.
</p>
<p>
<b>IMPORTANT NOTE:</b> In the explanations that follow it is assumed that
the Maze Simulator is installed into &lt;MRDS&gt;\ProMRDS\Chapter9\MazeSimulator.
</p>

<h2>How to run the Maze Simulator</h2>
<p>
You have the option of either re-building the program yourself or just using it.
If you do not want to build the code, or you don't have Microsoft
Visual Studio 2005, then the executables are included in the package
and they will be copied to your bin directory during installation.
</p>
<p>
As with all MRDS programs, you need to start the Maze Simulator from a MRDS DOS Command Prompt window,
or using the debugger in Visual Studio. Let's begin with running the program directly.
Make sure you have followed the installation instructions exactly.
</p>
<h3>Starting a MRDS Service</h3>
<p>
When you installed MRDS, it should have created a folder in your Start
Menu that contains a shortcut for "Microsoft Robotics Studio Command Prompt".
Open one of these windows now.
</p>
<p>
At the command prompt, enter the following command:<br />
<tt>dsshost -port:50000 -tcpport:50001 -manifest:"ProMRDS/Config/MazeSimulator.manifest.xml"</tt><br />
A batch file, called RunMazeSimulator.cmd, is included in the package to help make this easier.
It is located in the &lt;MRDS&gt;\bin folder.
<br />
<b>IMPORTANT NOTE:</b> dsshost.exe is the main control program for MRDS. It is responsible for
starting services, i.e. programs like the Maze Simulator. You must run it from the MRDS root directory
because it looks for various components starting from the current directory.
</p>
<h3>Using the Visual Studio Debugger</h3>
<p>
If you want to rebuild the code, then you must open the Solution in Visual Studio.
There are two ways to do this:<br />
From a MRDS Command Prompt window; or<br />
From Windows Explorer.
</p>
<p>To open the program from a DOS prompt, select "Microsoft Robotics Studio
Command Prompt" from the Start Menu, then start Visual Studio using the
following commands:<br />
<tt>cd ProMRDS\Chapter9\MazeSimulator<br />
devenv MazeSimulator.sln</tt><br />
</p>
<p>
To open the program using Windows Explorer, locate the .sln file which is
in the &lt;MRDS&gt;\ProMRDS\Chapter9\MazeSimulator directory and double-click on it.
</p>
<p>
Once the Solution is open in Visual Studio, you can start it with the debugger by
selecting Debug \ Start Debugging or pressing F5.<br />
<b>IMPORTANT NOTE:</b> Make sure that you have updated the Project settings if your
MRDS installation is not on the C: drive. 
</p>

<h2>Using the Maze Simulator program</h2>
<p>
When Maze Simulator starts, it will create two windows: A <a href="Images/SimulatorInitialView.jpg">Simulator</a>
and a <a href="Images/Dashboard.gif">Dashboard</a>. These are
shown below. Click on the images for larger views.
</p>
<a href="Images/SimulatorInitialView.jpg"><img src="Images/SimulatorInitialView_small.jpg" alt="Simulator View - Click for larger image" border="0" /></a>&nbsp;&nbsp;<a href="Images/Dashboard.gif"><img src="Images/Dashboard_small.gif" alt="Dashboard - Click for larger image" border="0" /></a>
<p>
The little object in the centre of the Simulation window is the Pioneer robot.
This maze world has textured walls and brightly colored objects. None of them
are moveable with the default settings, i.e. they all have infinite mass.
This is something you can change in the config file later if you want to be able
to push the walls around. However, there are some balls included in the sample
config file and you can push them around.
</p>
<p>
To change your viewpoint in the Simulator, click on the window and drag with
the mouse. You can also use the standard gaming keys, A, S, D and W, for
moving around. Note that A and D are strafe keys, not rotate. The S and W
keys move forwards and backwards along the line of sight. Use the mouse to
change the direction of motion by dragging on the simulation window.
The E and Q keys can be used to move
up and down. It's easy to get used to, especially if you are a gamer.
</p>
<p>
The Simulation Engine allows multiple cameras to be used. You can 
switch between cameras by pressing the F8 key in the Simulation window,
or selecting a camera from the Camera menu.</p>
<p>
The Maze Simulator has a camera located on top of the Pioneer robot (although you
can't see it). If you select the "robocam" camera from the Camera menu then you will
be able to see what the robot sees as it drives around. This is more fun,
and it is probably easier to drive the robot this way. A sample view from
the robot is shown below:
</p>
<img src="Images/RobotView.jpg" alt="Robot Webcam View" border="0" />
<p>
In the Dashboard, you must enter localhost as the name of the Remote
Node and Port number 50001. Then click on the Connect button.<br />
Two services will appear in the listbox. Double-click on the
<i>simulateddifferentialdrive</i> service, then click on the <b>Drive</b> button.
You are now ready to control the robot!
</p>
<p>
Note that the modified version of the Dashboard remembers
these settings so you only have to enter them once and then save them.
</p>
<p>
Use the mouse to drag on the trackball with the cross-hairs
(just above the <b>Stop</b> button). If you
drag left, the robot will rotate left; if you drag upwards, the robot
will move forwards; and so on. Take a while to get the hang of it. Just be aware
that the robot has inertia and will not move until you drag a
certain distance away from the centre. Also, it will not stop
immediately when you release the mouse button.
Drive around for a while to get the feel of the Simulator and the Dashboard.
</p>
<p>
You can also use a joystick or a game controller to control the robot.
It must be compatible with DirectX, but most joysticks are these days.
I have tested it using a Logitech Attack 3 USB joystick.
</p>
<p>
You can also turn on the Laser Range Finder by double-clicking on the
<i>simulatedlrf</i> service. You might have noticed red lines appearing
on the walls as the robot moves around. This is the laser. Now you will be able
to see in the Laser Range Finder panel a representation of what the robot thinks
it "sees" using the laser. It does not actually see walls like in the Dashboard,
this is just the way it is represented. Remember the laser scan is only in a
single horizontal plane at a fixed height off the ground.
</p>
<h2>Shutting down the Maze Simulator</h2>
<p>
When you get tired of playing, you can stop
the program by going back to the DOS window and typing Ctrl-C, i.e. hold
down Ctrl and press 'c'. This stops the dsshost program, and with it all of
the associated services that it started.
</p>
<p>
Alternatively, you can select Exit from the File menu in the Simulator.
</p>
<h2>Where to from here?</h2>
<p>
The Maze Simulator on its own is just a toy. The real power comes when you
learn how to write programs to control the simulated robot. For that you
need to download and install the <a href="Explorer.htm">Explorer Simulation</a>
program.
</p>
<p>
You should open the Maze Simulator in Visual Studio and look through it.
A lot of comments have been added to the code. The dssnewservice program
generated the basic structure. The basic skeleton of the code came from the
Microsoft Simulation Tutorials.
</p>
<p>
Now that you have run the Simulator, we suggest that you do the Microsoft Simulation Tutorials.
</p>

<p>
<a href="MazeSimulator.htm">[&nbsp;Overview&nbsp;]</a>&nbsp;|&nbsp;<a href="MazeSimulatorTutorial.htm">[&nbsp;Tutorial&nbsp;]</a>
</p>

</div>

<hr />
<div class="footer">
Page maintained by:
<a href="m&#97;&#105;&#108;t&#111;:webmaster&#64;promrds&#46;com">webmaster&#64;promrds.com</a><br />
Last Updated: Mar-2008
</div>

</body>
</html>
